\documentstyle[11pt,twoside,CMacs,Flow]{manual}
\tool{FLOW}{Typeset Flow diagrams in \LaTeX}{2}
\begin{document}

\maketitle

\begin{para}{Synopsis}
\verb"\STRUCT{struct name}{structure purpose}{statements}"

\vspace{0.25cm}
For a description of the statements see section Macros
\end{para}

\begin{para}{Description}
The {\tt Flow} macros enable the user to create flow diagrams in
a \LaTeX\ document. The macros can be used in any type of document, within all
the standard \LaTeX\ environments.

A flow diagram in this context is described in macros resembling a pseudo code.
The diagram itself is defined as a structure and is build from statements.
Macros are available for all standard programming statements (if, while, action
etc.).

The Language Sensitive Editor for \LaTeX, LSA, is extended to support the
creation of flow diagrams with the {\tt Flow} macros.

The macros needed to create a flow diagram in your \LaTeX\
document will be made available to you when you include the option \verb"Flow"
in the \verb"\documentstyle" command at the start of your \LaTeX\ file, as in
the following example:
\begin{verbatim}
\documentstyle[11pt,Flow]{article}
\end{verbatim}

A flow diagram in the context of the {\tt Flow} macros is called a structure.
The drawing of the diagram is based on units. A unit can be seen as the box in
which an action is described. The unit has an attribute, the width. It
determines the width of the boxes to be drawn. Users can change the with of
units through a macro which must be used before the actual structure is
described.

By default the text in the diagrams is typeset in the same size as the text in
the document. This will be to large.
Before starting a structure it is adviced to set the desired text size. For the 
default setting of the unit width \verb|\scriptsize| is recommended.

When you run into errors like {\tt overfull vbox[]} you may have to use a
smaller text size like \verb|\tiny|. In a default sized box 4 lines of
{\tt scriptsize} text can be placed. When {\tt tiny} is used 5 lines will fit.

Do not forget to reset the text size to {\tt normalsize} after the structure.
\end{para}

\begin{para}{Macros}

The available macros fall into three categories:

\begin{enumerate}
\item Width setting of the units. It must appear before the
structure.
\item Definition of the structure itself.
\item Statements. They must appear within the structure definition.
\end{enumerate}

\goodbreak
Width setting macro is:
\begin{itemize}

\nobreak
\item \verb"\unitwidth=size" \\
Specifies the minimum width of a unit. Size must be given as a standard \LaTeX\
length. 
\end{itemize}

\goodbreak
Structure definition macro is:
\begin{itemize}

\nobreak
\item \verb"\STRUCT{struct-name}{struct-description}{statements}%" \\
Specifies the complete diagram. The structure name will appear at the top of the
flow diagram and the description, which can be a short description of its
purpose, will be put beside the actual diagram. The statements of the structure,
described below, must be specified as part of the \verb"\STRUCT" command. 
\end{itemize}

\goodbreak
Statement macros are:
\begin{itemize}

\nobreak
\item \verb"\ACTION{action}%" \\
Specifies a normal statement. 

\item \verb"\PROC{proc-name}{proc-description}%" \\
Specifies a special kind of action, a procedure call. The proc-name will be put
below the proc-description text in the same box, separated by a horizontal line.

\item \verb"\LABEL{lab-name}%" \\
Specifies a label with a label-name of only a few letters.

\item \verb"\IF{condition}\THEN{statements}\ELSE{statements}\ENDIF%" \\
Specifies an if statement with a condition and a collection of statements in the
{\tt THEN} and the {\tt ELSE} part. Neither the {\tt THEN} nor the {\tt ELSE}
part is optional. If one of them is not needed an empty statement,
``\verb"{}"'', must be used. 

\item \verb"\REPEAT{statements}\UNTIL{test}%" \\
Specifies a loop statement with a collection of statements and an
end-condition. 

\item \verb"\WHILE{condition}{statements}\ENDWHILE%" \\
Specifies a loop statement with a start-condition and a collection of
statements. 

\item \verb"\CASE{case-item}{when-statements}\ENDCASE%" \\
Specifies a case statement with a case-item and a collection of when-statements. 

\item \verb"\WHEN{condition}{statements}%" \\
Part of a case statement. Specifies a condition and a collection of statements. 
\end{itemize}

\goodbreak
Options are:
\begin{itemize}

\nobreak
\item \verb"\setiftext{downward}{right-hand}%"\\
Specifies the text to be put on the downward and right-hand sides of the
condition of an if statement. By default the settings are empty. The scope for 
these settings depends on the position of the command within the document. 

\begin{itemize}
\item If the command occurs before a \verb"\STRUCT" statement, the settings
remain valid for all \verb"\IF" statements in all following structures until
they are reset by a \verb"\setiftext" command with the same scope. (Remember to
put the \verb"\setiftext" command {\bf after} any font size changing commands). 

\item If the command occurs inside a \verb"\STRUCT" statement but outside any
other commands, the settings will remain valid for all \verb"\IF" statements in
the same structure until they are reset by a \verb"\setiftext" command with the
same scope.

\item If the command occurs inside a command within a structure, the settings
will remain valid for all \verb"\IF" statements within the command (for
instance an if statement within the then or else part of another if statement)
until they are reset by a \verb"\setiftext" command with the same scope.

\end{itemize}

It is allowed to `nest' the \verb"\setiftext" commands, thus
changing the settings for a particular part of a structure or a document.

\end{itemize}

Note that each line within the structure, including the command itself,
{\em must} be concluded by a \%.

The text appearing (between the braces) in the structure definition and in all
statements is free but must adhere to the standard \LaTeX\ syntax. Every text is
considered a paragraph in the \LaTeX\ context. 
\end{para}

\begin{para}{Files}
The file \verb"TEX$INPUTS:FLOW.STY" specifies the flow macros.
\end{para}

\begin{para}{See also}
The pages on \LaTeX, LSA and NASSI in this section of the manual.
\end{para}

\begin{para}{Bugs}
The {\tt Flow} option is mutually exclusive with the {\tt Nassi} option
because the same macro names are used.

Always put the same number of actions in each branch ({\tt WHEN} statement) of a
{\tt CASE} statement. Only {\tt ACTION} and {\tt PROC} statements are allowed
here.


{\tt Flow} has a limit to the number of statement macro's in one structure
definition. For example a maximum of 26 IF macro's can be used. If one of these
limits is reached, \LaTeX\ shows some curious error messages, like ``You cannot
use = as a prefix'', which have no relation at all to the real problem.
\end{para}

\begin{para}{Example}
The following is an example of a structure with all possible statements. The
resulting diagram is shown below.

\begin{verbatim}
\scriptsize
\STRUCT{struct name}{structure purpose}{%
  \ACTION{initial statement}%
  \PROC{proc name}{procedure purpose}%
  \IF{condition\\ to test}%
  \THEN{%
    \ACTION{true action 1}%
    \ACTION{true action 2}%
  }%
  \ELSE{%
    \ACTION{false action}%
  }%
  \ENDIF%
  \LABEL{A}%
  \REPEAT{%
    \ACTION{statement to repeat}%
  }%
  \UNTIL{end condition}%
  \WHILE{start condition}{%
    \ACTION{statement to do}%
  }%
  \ENDWHILE%
  \CASE{case item}{%
    \WHEN{condition 1}{%
      \ACTION{statement to do}%
    }%
    \WHEN{condition 2}{%
      \ACTION{statement to do}%
    }%
    \WHEN{condition 3}{%
      \ACTION{statement to do}%
    }%
  }%
  \ENDCASE%
}%
\normalsize
\end{verbatim}
\end{para}

\newpage
\scriptsize
\STRUCT{struct name}{structure purpose}{%
  \ACTION{initial statement}%
  \PROC{proc name}{procedure purpose}%
  \IF{condition\\ to test}%
  \THEN{%
    \ACTION{true action 1}%
    \ACTION{true action 2}%
  }%
  \ELSE{%
    \ACTION{false action}%
  }%
  \ENDIF%
  \LABEL{A}%
  \REPEAT{%
    \ACTION{statement to repeat}%
  }%
  \UNTIL{end condition}%
  \WHILE{start condition}{%
    \ACTION{statement to do}%
  }%
  \ENDWHILE%
  \CASE{case item}{%
    \WHEN{condition 1}{%
      \ACTION{statement to do}%
    }%
    \WHEN{condition 2}{%
      \ACTION{statement to do}%
    }%
    \WHEN{condition 3}{%
      \ACTION{statement to do}%
    }%
  }%
  \ENDCASE%
}%
\normalsize

\end{document}
